Mobile to Address API - v1

This document highlights details of the Mobile to Address API v1.

API Description

Objective

The Mobile to Address API - v1 retrieves a user's verified address and contact details using their mobile number. It enables identity verification, contact-ability checks, and enhances skip tracing efforts.

Input	Output
The user's mobile number and consent	The address information, associated email ID, and delivery details

API URL

https://ind-engine.thomas.hyperverge.co/v1/mobileToAddress

API Endpoint

mobileToAddress

Overview

The Mobile to Address API - v1 is RESTful and uses standard HTTP verbs and status codes. The requests are in JSON format and responses are in JSON format.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing theThe Mobile to Address API - v1.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the The Mobile to Address API - v1's request body:

Parameter	Mandatory or Optional	Description
`mobileNo`	Mandatory	10 digit mobile number
`consent`	Mandatory	Consent flag indicating user permission (Y/N)

Request

The following code snippet demonstrates a standard curl request for the Mobile to Address API v1:

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/mobileToAddress' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
         "mobileNo":"<Enter_the_Mobile_Number>",
         "consent":"<Enter_Y_or_N>"
       }'

Success Response

The following code snippet demonstrates a success response from the Mobile to Address API v1:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "code": "1002",
    "message": "Fetched address data.",
    "addressData": [
      {
        "firstName": "<First_Name>",
        "email": "<Email_Address>",
        "isdCode": "+91",
        "line1": "<Address_Line_1>",
        "city": "<City_Name>",
        "state": "<State_Name>",
        "stateCode": "<State_Code>",
        "country": "India",
        "countryCode": "In",
        "pincode": "<Pincode>",
        "lastDeliveryDate": "<Last_Delivery_Date>"
      }
    ],
    "timestamp": <Timestamp>
  },
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the API response
statusCode	integer	The HTTP status code of the response
result	object	The main result object containing all response data
code	string	The internal code representing the operation result
message	string	The message describing the success response
addressData	array	The list of address records linked to the mobile number
firstName	string	The name or label associated with the address
email	string	The email ID associated with the address
isdCode	string	The country ISD code for the contact number
line1	string	The full address line including house/building and locality
city	string	The city of the address
state	string	The state of the address
stateCode	string	The two-letter code for the state
country	string	The country name
countryCode	string	The two-letter ISO country code
pincode	string	The postal code (ZIP or PIN code)
lastDeliveryDate	string	The last successful delivery date to this address
timestamp	number	The Unix timestamp of the API response in milliseconds
metadata	object	The metadata object containing request tracking information
requestId	string	The unique identifier for the request
transactionId	string	The unique identifier for the transaction

Failure Response

The following is a failure response from the API:

{
    "status": "failure",
    "statusCode": 404,
    "error": "No records found with given mobile number",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Responses

The following are some error responses from the API:

Invalid Mobile Number
Consent Not Provided
Missing/Invalid Credentials
Internal Server Error
External Source Downtime

{
    "status": "failure",
    "statusCode": 400,
    "error": "Invalid mobile number",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "status": "failure",
    "statusCode": 400,
    "error": "Consent not provided",
    "metadata": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error"
}

{
    "status": "failure",
    "statusCode": 503,
    "error": "External source downtime"
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Description
400	Invalid mobile number	The mobile number provided is not in valid format
400	Consent not provided	The consent is missing or invalid
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
404	No records found with given mobile number	The mobile number provided does not exist in the database
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	External source downtime	Please contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

Inputs​

Request​

Success Response​

Success Response Details​

Failure Response​

Error Responses​

Failure and Error Response Details​